/*
 * Copyright 2007
 * On2 Technologies Incorporated
 *
 * All rights reserved.
 *
 * $Id$
 */
/*!\defgroup decoder Common Decoder Algorithm Interface
 * This abstraction allows applications using this decoder to easily support
 * multiple video formats with minimal code duplication. This section describes
 * the interface common to all codecs.
 * @{
 */
 
/*!\file on2_decoder_compat.h
 * \brief Provides a compatibility layer between version 1 and 2 of this API.
 *
 * This interface has been deprecated. Only existing code should make use
 * of this interface, and therefore, it is only thinly documented. Existing
 * code should be ported to the on2_codec_* API.
 */
#ifndef ON2_DECODER_COMPAT_H
#define ON2_DECODER_COMPAT_H

#ifndef DEPRECATED
#if defined(__GNUC__) && __GNUC__
#define DEPRECATED __attribute__ ((deprecated))
#else
#define DEPRECATED
#endif
#endif

/*!\brief Decoder algorithm return codes */
typedef enum {
    /*!\brief Operation completed without error */
    ON2_DEC_OK = ON2_CODEC_OK,
    
    /*!\brief Unspecified error */
    ON2_DEC_ERROR = ON2_CODEC_ERROR,
    
    /*!\brief Memory operation failed */
    ON2_DEC_MEM_ERROR = ON2_CODEC_MEM_ERROR,
    
    /*!\brief ABI version mismatch */
    ON2_DEC_ABI_MISMATCH = ON2_CODEC_ABI_MISMATCH,
    
    /*!\brief The given bitstream is not supported.
     *
     * The bitstream was unable to be parsed at the highest level. The decoder
     * is unable to proceed. This error \ref SHOULD be treated as fatal to the
     * stream. */
    ON2_DEC_UNSUP_BITSTREAM = ON2_CODEC_UNSUP_BITSTREAM,
    
    /*!\brief Encoded bitstream uses an unsupported feature
     *
     * The decoder does not implement a feature required by the encoder. This
     * return code should only be used for features that prevent future
     * pictures from being properly decoded. This error \ref MAY be treated as
     * fatal to the stream or \ref MAY be treated as fatal to the current GOP.
     */
    ON2_DEC_UNSUP_FEATURE = ON2_CODEC_UNSUP_FEATURE,
    
    /*!\brief The coded data for this stream is corrupt or incomplete
     *
     * There was a problem decoding the current frame.  This return code
     * should only be used for failures that prevent future pictures from
     * being properly decoded. This error \ref MAY be treated as fatal to the
     * stream or \ref MAY be treated as fatal to the current GOP. If decoding
     * is continued for the current GOP, artifacts may be present.
     */
    ON2_DEC_CORRUPT_FRAME = ON2_CODEC_CORRUPT_FRAME,
    
    /*!\brief An application-supplied parameter is not valid.
     *
     */
    ON2_DEC_INVALID_PARAM = ON2_CODEC_INVALID_PARAM,
    
    /*!\brief An iterator reached the end of list.
     *
     */
    ON2_DEC_LIST_END = ON2_CODEC_LIST_END,
    
} on2_dec_err_t;

/*! \brief Decoder capabilities bitfield
 *
 *  Each decoder advertises the capabilities it supports as part of its
 *  ::on2_dec_iface_t interface structure. Capabilities are extra interfaces
 *  or functionality, and are not required to be supported by a decoder.
 *
 *  The available flags are specifiedby ON2_DEC_CAP_* defines. 
 */
typedef int on2_dec_caps_t;
#define ON2_DEC_CAP_PUT_SLICE  0x0001 /**< Will issue put_slice callbacks */
#define ON2_DEC_CAP_PUT_FRAME  0x0002 /**< Will issue put_frame callbacks */
#define ON2_DEC_CAP_XMA        0x0004 /**< Supports eXternal Memory Allocation */

/*!\brief Stream properties
 *
 * This structure is used to query or set properties of the decoded
 * stream. Algorithms may extend this structure with data specific
 * to their bitstream by setting the sz member appropriately.
 */
#if 1
typedef on2_codec_stream_info_t on2_dec_stream_info_t;
#else
typedef struct {
    unsigned int sz;     /**< Size of this structure */
    unsigned int w;      /**< Width (or 0 for unknown/default) */
    unsigned int h;      /**< Height (or 0 for unknown/default) */
    unsigned int is_kf;  /**< Current frame is a keyframe */
} on2_dec_stream_info_t;
#endif


/*!\brief Decoder interface structure.
 *
 * Contains function pointers and other data private to the decoder
 * implementation. This structure is opaque to the application.
 */
typedef const struct on2_codec_iface on2_dec_iface_t;
typedef       struct on2_codec_priv  on2_dec_priv_t;

/*!\brief Iterator
 *
 * Opaque storage used for iterating over lists.
 */
typedef on2_codec_iter_t on2_dec_iter_t;

/*!\brief Decoder context structure
 *
 * All decoders \ref MUST support this context structure fully. In general,
 * this data should be considered private to the decoder algorithm, and 
 * not be manipulated or examined by the calling application. Applications
 * may reference the 'name' member to get a printable description of the
 * algorithm.
 */
#if 1
typedef on2_codec_ctx_t on2_dec_ctx_t;
#else
typedef struct {
    const char*            name;        /**< Printable interface name */
    on2_dec_iface_t       *iface;       /**< Interface pointers */
    on2_dec_err_t          err;         /**< Last returned error */         
    on2_dec_priv_t        *priv;        /**< Algorithm private storage */
} on2_dec_ctx_t;
#endif


/*!\brief Return the build configuration
 *
 * Returns a printable string containing an encoded version of the build
 * configuration. This may be useful to On2 support.
 *
 */
const char *on2_dec_build_config(void) DEPRECATED;

/*!\brief Return the name for a given interface
 *
 * Returns a human readable string for name of the given decoder interface.
 *
 * \param[in]    iface     Interface pointer
 *
 */
const char *on2_dec_iface_name(on2_dec_iface_t *iface) DEPRECATED;


/*!\brief Convert error number to printable string
 *
 * Returns a human readable string for the last error returned by the
 * algorithm. The returned error will be one line and will not contain
 * any newline characters.
 *
 *
 * \param[in]    err     Error number.
 *
 */
const char *on2_dec_err_to_string(on2_dec_err_t  err) DEPRECATED;


/*!\brief Retrieve error synopsis for decoder context
 *
 * Returns a human readable string for the last error returned by the
 * algorithm. The returned error will be one line and will not contain
 * any newline characters.
 *
 *
 * \param[in]    ctx     Pointer to this instance's context.
 *
 */
const char *on2_dec_error(on2_dec_ctx_t  *ctx) DEPRECATED;


/*!\brief Retrieve detailed error information for decoder context
 *
 * Returns a human readable string providing detailed information about
 * the last error. 
 *
 * \param[in]    ctx     Pointer to this instance's context.
 *
 * \retval NULL
 *     No detailed information is available.
 */
const char *on2_dec_error_detail(on2_dec_ctx_t  *ctx) DEPRECATED;


/* REQUIRED FUNCTIONS
 *
 * The following functions are required to be implemented for all decoders.
 * They represent the base case functionality expected of all decoders.
 */

 
/*!\brief Initialize a decoder instance
 *
 * Initializes a decoder context using the given interface. Applications
 * should call the on2_dec_init convenience macro instead of this
 * function directly, to ensure that the ABI version number parameter
 * is properly initialized.
 *
 * \param[in]    ctx     Pointer to this instance's context.
 * \param[in]    iface   Pointer to the alogrithm interface to use.
 * \param[in]    ver     ABI version number. Must be set to 
 *                       ON2_DECODER_ABI_VERSION
 * \retval #ON2_DEC_OK
 *     The decoder algorithm initialized.
 * \retval #ON2_DEC_MEM_ERROR
 *     Memory allocation failed.
 */
on2_dec_err_t on2_dec_init_ver(on2_dec_ctx_t    *ctx,
                	       on2_dec_iface_t  *iface,
			       int               ver) DEPRECATED;
#define on2_dec_init(ctx, iface) \
    on2_dec_init_ver(ctx, iface, ON2_DECODER_ABI_VERSION)


/*!\brief Destroy a decoder instance
 *
 * Destroys a decoder context, freeing any associated memory buffers.
 *
 * \param[in] ctx   Pointer to this instance's context
 *
 * \retval #ON2_DEC_OK
 *     The decoder algorithm initialized.
 * \retval #ON2_DEC_MEM_ERROR
 *     Memory allocation failed.
 */
on2_dec_err_t on2_dec_destroy(on2_dec_ctx_t *ctx) DEPRECATED;


/*!\brief Get the capabilities of an algorithm.
 *
 * Retrieves the capabliities bitfield from the algorithm's interface.
 *
 * \param[in] iface   Pointer to the alogrithm interface
 *
 */
on2_dec_caps_t on2_dec_get_caps(on2_dec_iface_t *iface) DEPRECATED;


/*!\brief Parse stream info from a buffer
 *
 * Performs high level parsing of the bitstream. Construction of a decoder
 * context is not necessary. Can be used to determine if the bitstream is
 * of the proper format, and to extract information from the stream.
 *
 * \param[in]      iface   Pointer to the alogrithm interface
 * \param[in]      data    Pointer to a block of data to parse
 * \param[in]      data_sz Size of the data buffer
 * \param[in,out]  si      Pointer to stream info to update. The size member
 *                         \ref MUST be properly initialized, but \ref MAY be
 *                         clobbered by the algorithm. This parameter \ref MAY
 *                         be NULL.
 *
 * \retval #ON2_DEC_OK
 *     Bitstream is parsable and stream information updated
 */
on2_dec_err_t on2_dec_peek_stream_info(on2_dec_iface_t       *iface,
                        	       const uint8_t         *data,	  
                        	       unsigned int           data_sz,
                        	       on2_dec_stream_info_t *si) DEPRECATED;


/*!\brief Return information about the current stream.
 *
 * Returns information about the stream that has been parsed during decoding.
 *
 * \param[in]      ctx     Pointer to this instance's context
 * \param[in,out]  si      Pointer to stream info to update. The size member
 *                         \ref MUST be properly initialized, but \ref MAY be
 *                         clobbered by the algorithm. This parameter \ref MAY
 *                         be NULL.
 *
 * \retval #ON2_DEC_OK
 *     Bitstream is parsable and stream information updated
 */
on2_dec_err_t on2_dec_get_stream_info(on2_dec_ctx_t         *ctx,
                                      on2_dec_stream_info_t *si) DEPRECATED;


/*!\brief Control algorithm
 *
 * This function is used to exchange algorithm specific data with the decoder
 * instance. This can be used to implement features specific to a particular
 * algorithm. 
 *
 * This wrapper function dispatches the request to the helper function
 * associated with the given ctrl_id. It tries to call this function
 * transparantly, but will return #ON2_DEC_ERROR if the request could not
 * be dispatched. 
 *
 * \param[in]     ctx              Pointer to this instance's context
 * \param[in]     ctrl_id          Algorithm specific control identifier
 * \param[in,out] data             Data to exchange with algorithm instance. 
 *
 * \retval #ON2_DEC_OK
 *     The control request was processed.
 * \retval #ON2_DEC_ERROR
 *     The control request was not processed.
 * \retval #ON2_DEC_INVALID_PARAM
 *     The data was not valid.
 */
on2_dec_err_t on2_dec_control(on2_dec_ctx_t  *ctx,
                	      int             ctrl_id,     
                	      void           *data) DEPRECATED;	    

/*!\brief Decode data
 *
 * Processes a buffer of coded data. If the processing results in a new
 * decoded frame becoming available, #ON2_DEC_CB_PUT_SLICE and 
 * #ON2_DEC_CB_PUT_FRAME events may be generated, as appropriate. Encoded data
 * \ref MUST be passed in DTS (decode time stamp) order. Frames produced will
 * always be in PTS (presentation time stamp) order.
 *
 * \param[in] ctx          Pointer to this instance's context
 * \param[in] data         Pointer to this block of new coded data. If
 *                         NULL, a ON2_DEC_CB_PUT_FRAME event is posted
 *                         for the previously decoded frame.
 * \param[in] data_sz      Size of the coded data, in bytes.
 * \param[in] user_priv    Application specific data to associate with 
 *                         this frame.
 * \param[in] rel_pts      PTS relative to the previous frame, in us. If
 *                         unknown or unavailable, set to zero.
 *
 * \return Returns #ON2_DEC_OK if the coded data was processed completely
 *         and future pictures can be decoded without error. Otherwise,
 *         see the descriptions of the other error codes in ::on2_dec_err_t
 *         for recoverability capabilities.
 */
on2_dec_err_t on2_dec_decode(on2_dec_ctx_t	*ctx,
                	     uint8_t		*data,     
                	     unsigned int	 data_sz,
                	     void		*user_priv,
			     int		 rel_pts) DEPRECATED;     


/*!\brief Decoded frames iterator
 *
 * Iterates over a list of the frames available for display. The iterator
 * storage should be initialized to NULL to start the iteration. Iteration is
 * complete when this function returns NULL.
 *
 * The list of available frames becomes valid upon completion of the
 * on2_dec_decode call, and remains valid until the next call to on2_dec_decode.
 *
 * \param[in]     ctx      Pointer to this instance's context
 * \param[in out] iter     Iterator storage, initialized to NULL
 *
 * \return Returns a pointer to an image, if one is ready for display. Frames
 *         produced will always be in PTS (presentation time stamp) order.
 */
on2_image_t *on2_dec_get_frame(on2_dec_ctx_t  *ctx,
                               on2_dec_iter_t *iter) DEPRECATED;
 

/*!\defgroup cap_put_frame Frame-Based Decoding Functions
 *
 * The following functions are required to be implemented for all decoders
 * that advertise the ON2_DEC_CAP_PUT_FRAME capability. Calling these functions
 * for codecs that don't advertise this capability will result in an error
 * code being returned, usually ON2_DEC_ERROR
 * @{
 */
 
/*!\brief put frame callback prototype
 *
 * This callback is invoked by the decoder to notify the application of
 * the availability of decoded image data.
 */
typedef void (*on2_dec_put_frame_cb_fn_t) (void 	     *user_priv, 
                                           const on2_image_t *img);


/*!\brief Register for notification of frame completion.
 *
 * Registers a given function to be called when a decoded frame is
 * available.
 *
 * \param[in] ctx          Pointer to this instance's context
 * \param[in] cb           Pointer to the callback function
 * \param[in] user_priv    User's private data
 *
 * \retval #ON2_DEC_OK
 *     Callback successfully registered.
 * \retval #ON2_DEC_ERROR
 *     Decoder context not initialized, or algorithm not capable of 
 *     posting slice completion.
 */
on2_dec_err_t on2_dec_register_put_frame_cb(on2_dec_ctx_t             *ctx,
                                	    on2_dec_put_frame_cb_fn_t  cb,
					    void                      *user_priv) DEPRECATED;


/*!@} - end defgroup cap_put_frame */

/*!\defgroup cap_put_slice Slice-Based Decoding Functions
 *
 * The following functions are required to be implemented for all decoders
 * that advertise the ON2_DEC_CAP_PUT_SLICE capability. Calling these functions
 * for codecs that don't advertise this capability will result in an error
 * code being returned, usually ON2_DEC_ERROR
 * @{
 */
 
/*!\brief put slice callback prototype
 *
 * This callback is invoked by the decoder to notify the application of
 * the availability of partially decoded image data. The 
 */
typedef void (*on2_dec_put_slice_cb_fn_t) (void 		  *user_priv, 
                                           const on2_image_t	  *img,       
					   const on2_image_rect_t *valid,     
					   const on2_image_rect_t *update);   


/*!\brief Register for notification of slice completion.
 *
 * Registers a given function to be called when a decoded slice is
 * available.
 *
 * \param[in] ctx          Pointer to this instance's context
 * \param[in] cb           Pointer to the callback function
 * \param[in] user_priv    User's private data
 *
 * \retval #ON2_DEC_OK
 *     Callback successfully registered.
 * \retval #ON2_DEC_ERROR
 *     Decoder context not initialized, or algorithm not capable of 
 *     posting slice completion.
 */
on2_dec_err_t on2_dec_register_put_slice_cb(on2_dec_ctx_t             *ctx,
                                	    on2_dec_put_slice_cb_fn_t  cb,
					    void                      *user_priv) DEPRECATED;


/*!@} - end defgroup cap_put_slice*/

/*!\defgroup cap_xma External Memory Allocation Functions
 *
 * The following functions are required to be implemented for all decoders
 * that advertise the ON2_DEC_CAP_XMA capability. Calling these functions
 * for codecs that don't advertise this capability will result in an error
 * code being returned, usually ON2_DEC_ERROR
 * @{
 */

/*!\brief Memory Map Entry
 *
 * This structure is used to contain the properties of a memory segment. It
 * is populated by the decoder in the request phase, and by the calling
 * application once the requested allocation has been performed.
 */
#if 1
#define ON2_DEC_MEM_ZERO     0x1  /**< Segment must be zeroed by allocation */
#define ON2_DEC_MEM_WRONLY   0x2  /**< Segment need not be readable */
#define ON2_DEC_MEM_FAST     0x4  /**< Place in fast memory, if available */
typedef struct on2_codec_mmap on2_dec_mmap_t;
#else
typedef struct on2_dec_mmap {
    /*
     * The following members are set by the codec when requesting a segment
     */
    unsigned int   id;     /**< identifier for the segment's contents */
    unsigned long  sz;     /**< size of the segment, in bytes */
    unsigned int   align;  /**< required alignment of the segment, in bytes */
    unsigned int   flags;  /**< bitfield containing segment properties */
#define ON2_DEC_MEM_ZERO     0x1  /**< Segment must be zeroed by allocation */
#define ON2_DEC_MEM_WRONLY   0x2  /**< Segment need not be readable */
#define ON2_DEC_MEM_FAST     0x4  /**< Place in fast memory, if available */

    /* The following members are to be filled in by the allocation function */    
    void          *base;   /**< pointer to the allocated segment */
    void         (*dtor)(struct on2_dec_mmap *map); /**< destructor to call */
    void          *priv;   /**< allocator private storage */
} on2_dec_mmap_t;
#endif

/*!\brief Initialize a decoder instance in external allocation mode
 *
 * Initializes a decoder context using the given interface. Applications
 * should call the on2_dec_xma_init convenience macro instead of this
 * function directly, to ensure that the ABI version number parameter
 * is properly initialized.
 *
 * \param[in]    ctx     Pointer to this instance's context.
 * \param[in]    iface   Pointer to the alogrithm interface to use.
 * \param[in]    ver     ABI version number. Must be set to 
 *                       ON2_DECODER_ABI_VERSION
 * \retval #ON2_DEC_OK
 *     The decoder algorithm initialized.
 * \retval #ON2_DEC_ERROR
 *     Decoder does not support XMA mode.
 */
on2_dec_err_t on2_dec_xma_init_ver(on2_dec_ctx_t    *ctx,
                		   on2_dec_iface_t  *iface,
				   int               ver) DEPRECATED;
#define on2_dec_xma_init(ctx, iface) \
    on2_dec_xma_init_ver(ctx, iface, ON2_DECODER_ABI_VERSION)


/*!\brief Iterate over the list of segments to allocate.
 *
 * Iterates over a list of the segments to allocate. The iterator storage
 * should be initialized to NULL to start the iteration. Iteration is complete
 * when this function returns ON2_DEC_LIST_END. The amount of memory needed to
 * allocate is dependant upon the size of the encoded stream. This means that
 * the stream info structure must be known at allocation time. It can be
 * populated with the on2_dec_peek_stream_info() function. In cases where the
 * stream to be decoded is not available at allocation time, a fixed size must
 * be requested. The decoder will not be able to decode streams larger than
 * the size used at allocation time.
 *
 * \param[in]      ctx     Pointer to this instance's context.
 * \param[out]     mmap    Pointer to the memory map entry to populate.
 * \param[in]      si	   Pointer to the stream info.
 * \param[in out]  iter    Iterator storage, initialized to NULL
 *
 * \retval #ON2_DEC_OK
 *     The memory map entry was populated.
 * \retval #ON2_DEC_ERROR
 *     Decoder does not support XMA mode.
 * \retval #ON2_DEC_MEM_ERROR
 *     Unable to determine segment size from stream info.
 */
on2_dec_err_t on2_dec_get_mem_map(on2_dec_ctx_t                *ctx,
                                  on2_dec_mmap_t               *mmap,
				  const on2_dec_stream_info_t  *si,
                                  on2_dec_iter_t               *iter) DEPRECATED;


/*!\brief Identify allocated segments to decoder instance
 *
 * Stores a list of allocated segments in the decoder. Segments \ref MUST be
 * passed in the order they are read from on2_dec_get_mem_map(), but may be
 * passed in groups of any size. Segments \ref MUST be set only once. The
 * allocation function \ref MUST ensure that the on2_dec_mmap_t::base member
 * is non-NULL. If the segment requires cleanup handling (eg, calling free()
 * or close()) then the on2_dec_mmap_t::dtor member \ref MUST be populated.
 *
 * \param[in]      ctx     Pointer to this instance's context.
 * \param[in]      mmaps   Pointer to the first memory map entry in the list.
 * \param[in]      num_maps  Number of entries being set at this time
 *
 * \retval #ON2_DEC_OK
 *     The segment was stored in the decoder context.
 * \retval #ON2_DEC_ERROR
 *     Decoder does not support XMA mode.
 * \retval #ON2_DEC_MEM_ERROR
 *     Segment base address was not set, or segment was already stored.
 
 */
on2_dec_err_t  on2_dec_set_mem_map(on2_dec_ctx_t   *ctx,
                                   on2_dec_mmap_t  *mmaps,
                                   unsigned int     num_maps) DEPRECATED;

/*!@} - end defgroup cap_xma*/
/*!@} - end defgroup decoder*/

				    
#endif
